"""

Template module for Scripts

Copy this module up one level to gamesrc/scripts and name it
appropriately, then use that as a template to create your own script.

Test scripts in-game e.g. with the @script command. In code you can
create new scripts of a given class with
  script = ev.create.script("path.to.module.and.class")

Scripts are objects that handle everything in the game having
a time-component (i.e. that may change with time, with or without
a player being involved in the change). Scripts can work like "events",
in that they are triggered at regular intervals to do a certain script,
but an Script set on an object can also be responsible for silently
checking if its state changes, so as to update it. Evennia use several
in-built scripts to keep track of things like time, to clean out
dropped connections etc.

"""

from ev import Script

class ExampleScript(BaseScript):
    """
    A script type is customized by redefining some or all of its hook methods and variables.

    * available properties

     key (string) - name of object
     name (string)- same as key
     aliases (list of strings) - aliases to the object. Will be saved to database as AliasDB entries but returned as strings.
     dbref (int, read-only) - unique #id-number. Also "id" can be used.
     dbobj (Object, read-only) - link to database model. dbobj.typeclass points back to this class
     typeclass (Object, read-only) - this links back to this class as an identified only. Use self.swap_typeclass() to switch.
     date_created (string) - time stamp of object creation
     permissions (list of strings) - list of permission strings

     desc (string)      - optional description of script, shown in listings
     obj (Object)       - optional object that this script is connected to and acts on (set automatically by obj.scripts.add())
     interval (int)     - how often script should run, in seconds. <0 turns off ticker
     start_delay (bool) - if the script should start repeating right away or wait self.interval seconds
     repeats (int)      - how many times the script should repeat before stopping. 0 means infinite repeats
     persistent (bool)  - if script should survive a server shutdown or not
     is_active (bool)   - if script is currently running

    * Handlers

     locks - lock-handler: use locks.add() to add new lock strings
     db - attribute-handler: store/retrieve database attributes on this self.db.myattr=val, val=self.db.myattr
     ndb - non-persistent attribute handler: same as db but does not create a database entry when storing data

    * Helper methods

     start() - start script (this usually happens automatically at creation and obj.script.add() etc)
     stop()  - stop script, and delete it
     pause() - put the script on hold, until unpause() is called. If script is persistent, the pause state will survive a shutdown.
     unpause() - restart a previously paused script. The script will continue as if it was never paused.
     time_until_next_repeat() - if a timed script (interval>0), returns time until next tick

    * Hook methods (should also include self as the first argument):

     at_script_creation() - called only once, when an object of this
                            class is first created.
     is_valid() - is called to check if the script is valid to be running
                  at the current time. If is_valid() returns False, the running
                  script is stopped and removed from the game. You can use this
                  to check state changes (i.e. an script tracking some combat
                  stats at regular intervals is only valid to run while there is
                  actual combat going on).
      at_start() - Called every time the script is started, which for persistent
                  scripts is at least once every server start. Note that this is
                  unaffected by self.delay_start, which only delays the first call
                  to at_repeat().
      at_repeat() - Called every self.interval seconds. It will be called immediately
                  upon launch unless self.delay_start is True, which will delay
                  the first call of this method by self.interval seconds. If
                  self.interval==0, this method will never be called.
      at_stop() - Called as the script object is stopped and is about to be removed from
                  the game, e.g. because is_valid() returned False.
      at_server_reload() - Called when server reloads. Can be used to save temporary
                  variables you want should survive a reload.
      at_server_shutdown() - called at a full server shutdown.

    """
    pass
